home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / gnu / gawk / gawk213s.zoo / gawk-src-2.13 / vms / gawk.hlp < prev    next >
Text File  |  1991-06-19  |  59KB  |  1,157 lines
  1. ! Gawk.Hlp
  2. !                                                       Pat Rankin, Jun'90
  3. !                                                          revised, Jun'91
  4. !   Online help for GAWK.
  5. !
  6. 1 GAWK
  7.  GAWK is GNU awk, the Free Software Foundation's implementation of
  8.  the awk programming language.  awk is an interperative language which
  9.  can handle many data-reformatting jobs with just a few lines of code.
  10.  It has powerful string manipulation and pattern matching capabilities
  11.  built in.  This version should be compatable with POSIX 1003.2 awk.
  12.  
  13.  The VMS version of GAWK supports both the original UN*X-style command
  14.  interface and a DCL interface.  The only setup requirement for GAWK
  15.  is to define it as a 'foreign' command:  a DCL symbol with a value
  16.  which begins with '$'.
  17.        $ GAWK :== $disk:[directory]GAWK
  18. 2 GNU_syntax
  19.  GAWK's UN*X-style interface uses the 'dash' convention for specifying
  20.  options and uses spaces to separate multiple arguments.
  21.  
  22.  There are two main alternatives, depending on how the awk program is
  23.  to be passed to GAWK.  Both alternatives share most options.
  24.  
  25.  Usage: $ gawk [-W opts] [-F fs] [-v var=val] -f progfile [--] file ...
  26.     or  $ gawk [-W opts] [-F fs] [-v var=val] [--] "program" file ...
  27.  
  28.  The options are case-sensitive.  On VMS, the DCL command interpreter
  29.  converts unquoted text into uppercase before passing it to the running
  30.  program.  However, GAWK is written in 'C' and the C Run-Time Library
  31.  (VAXCRTL) converts unquoted text into *lowercase*.  Therefore, the
  32.  -Fval and -W options must be enclosed in quotes.
  33. 3 options
  34.  -f file    use the specified file as the awk program source; if more
  35.             than one instance of -f is used, each file will be read
  36.             in succession
  37.  -Fstring   define a value for the FS variable (field separator)
  38.  -v var=val assign a value of 'val' to the variable 'var'
  39.  -W 'options'  additional gawk-specific options; multiple values may
  40.             be separated by commas, or by spaces if they're quoted,
  41.             or mulitple occurences of -W may be used.
  42.  -W compat  use awk "compatibility mode" to disable GAWK extensions
  43.             and get the behavior of UN*X awk.
  44.  -W copyright [or -W copyleft]  display an abbreivated version of
  45.             the GNU copyright information
  46.  -W lint    warn about suspect or non-portable awk program code
  47.  -W posix   compatibility mode with additional restrictions
  48.  -W version display program version number
  49.  --         don't check further arguments for leading dash
  50. 3 program_text
  51.  If the '-f file' option is not used on the command line, then the
  52.  first "non-dash" argument is assumed to be a string of text containing
  53.  the awk source program.  Here is a complete sample program:
  54.        $ gawk -- "BEGIN {print ""\nHello, World!\n""}"
  55.  This program would print a blank line (based on first "\n"), followed
  56.  by a line reading "Hello, World!", followed by another blank line
  57.  (since awk's 'print' statement includes trailing 'newline').
  58.  
  59.  On VMS, to include a quote character inside of a quoted string, two
  60.  successive quotes ("") must be used.
  61. 3 data_files
  62.  After all dash-options are examined, and after the program text if
  63.  there were no occurences of the -f option, remaining (space separated)
  64.  command line arguments are considered to be data files for the awk
  65.  program to process.  If any of these actually contains an equals sign
  66.  (=), then it is interpreted as a variable assignment instead of a data
  67.  file.  The syntax is 'variable_name=value'.  For example, the command
  68.        $ gawk -f myprog.awk infile.one flag=2 start=0 infile.two
  69.  would read file 'infile.one' for the program in 'myprog.awk', then it
  70.  would set 'flag' to 2 and 'start' to 0, and finally it would read file
  71.  'infile.two' for the program.  Note that in a case like this, the two
  72.  assignments actually occur after the first file has been processed,
  73.  not at program startup when the command line is first scanned.
  74. 3 IO_redirection
  75.  The command parsing in the VMS implementation of GAWK does some
  76.  emulation of a UN*X-style shell, where certain characters on the
  77.  command line have special meaning.  In particular, the symbols '<',
  78.  '>', '|', '*', and '?' receive special handling before the main part
  79.  of the program has a chance to see them.  The symbols '<' and '>'
  80.  perform some file manipulation from the command line:
  81.  
  82.  <ifile     open file 'ifile' (readonly) as 'stdin' [SYS$INPUT]
  83.  >nfile     create 'nfile' at 'stdout' [SYS$OUTPUT], in stream-lf format
  84.  >>ofile    append to 'ofile' for 'stdout'; create it if necessary
  85.  >&efile    point 'stderr' [SYS$ERROR] at 'efile', but don't open it yet
  86.  >$vfile    create 'vfile' as 'stdout', using RMS attributes appropriate
  87.             for a standard text file (variable length records with
  88.             implied carriage control)
  89.  2>&1       route error messages into the regular output stream
  90.  1>&2       send output data to the error destination
  91.  <<sentinal error; reading stdin until 'sentinal' not supported
  92.  <-, >-     error; closer of stdin or stdout from cmd line not supported
  93.  >>$vfile   incorrect; would be interpreted as file "$vfile" in stream-lf
  94.             format rather than as file "vfile" in RMS 'text' format
  95.  |          error; command line pipes not supported
  96. 3 wildcard_expansion
  97.  The command parsing in the VMS implementation of GAWK does some
  98.  emulation of a UN*X-style shell, where certain characters on the
  99.  command line have special meaning.  In particular, the symbols '<',
  100.  '>', '*', '%', and '?' receive special handling before the main part
  101.  of the program has a chance to see them.  The symbols '*', '%' and '?'
  102.  are used as wildcards in filenames.  '*' and '%' have their usual VMS
  103.  meanings of multiple character and single character wildcards,
  104.  respectively, and '?' is also treated as a single character wildcard.
  105.  
  106.  When a command line argument that should be a filename contains any
  107.  of the wildcard characters, a directory lookup is attempted for files
  108.  which match the specified pattern.  If one or more matching files are
  109.  found, those filenames are put into the command line in place of the
  110.  original pattern.  If no matching files are found, the original
  111.  pattern is left in place.
  112. 2 DCL_syntax
  113.  GAWK's DCL-style interface is more or less a standard DCL command, with
  114.  one required parameter.  Multiple values--when present--are separated
  115.  by commas.
  116.  
  117.  There are two main alternatives, depending on how the awk program is
  118.  to be passed to GAWK.  Both alternatives share most options.
  119.  
  120.  Usage:  GAWK  /COMMANDS="awk program text"  data_file[,data_file,...]
  121.     or   GAWK  /INPUT=awk_file  data_file[,"Var=value",data_file,...]
  122.  (  or   GAWK  /INPUT=(awk_file1,awk_file2,...)  data_file[,...]       )
  123. 3 Parameter
  124.  data_file[,datafile,...]       (data_file data_file ...)
  125.  data_file[,"Var=value",...,data_file,...]      (data_file Var=value &c)
  126.  
  127.   Data file(s) for the awk program to process.  If any of these
  128.   actually contains an equals sign (=), then it is interpreted as
  129.   a variable assignment instead of a data file.  The syntax is
  130.   "variable_name=value".  Quotes are required for non-file parameters.
  131.  
  132.   For example, the command
  133.        $ gawk/input=myprog.awk infile.one,"flag=2","start=0",infile.two
  134.   would read file 'infile.one' for the program in 'myprog.awk', then it
  135.   would set 'flag' to 2 and 'start' to 0, and finally it would read file
  136.   'infile.two' for the program.  Note that in a case like this, the two
  137.   assignments actually occur after the first file has been processed,
  138.   not at program startup when the command line is first scanned.
  139.  
  140.   Wildcard file lookups are attempted on data file specifications.  See
  141.   subtopic 'GAWK GNU_syntax wildcard_expansion' for details.
  142.  
  143.   At least one data_file parameter value is required.  An exception is
  144.   made if /usage, /version, or /copyright is specifed *and* if GAWK is
  145.   defined as a 'foreign' command rather than a 'native' DCL command.
  146. 3 Qualifiers
  147. /COMMANDS
  148.  /COMMANDS="awk program text"   (-- "awk program text")
  149.  
  150.   For short programs, it is possible to include the complete program
  151.   on the command line.  The quotes are required.  Here is a complete
  152.   sample program:
  153.        $ gawk/commands="BEGIN {print ""\nHello, W